It's a subtle difference, but one-time use refers to the value of the refresh token, which you use against the /oauth2/token endpoint to get a new access token via the refresh grant.

A sliding window refers to the refresh token itself, which has a unique id which stays the same, even as the value of the refresh token changes.

So if you had a refresh token with a lifetime of 4 hours, a sliding window and one time use configured, you might end up with something like this:

at creation: id 09cfb961-291a-420f-b5cf-48c5c87a67cc, value RNhY5yE39t1o2FXKxgyH, lifetime 4 hours when the RT is presented to the /oauth2/token endpoint 3 hours after creation: id 09cfb961-291a-420f-b5cf-48c5c87a67cc, value Fh95KZLfSMjMNxpR5B4c, lifetime 4 more hours when the RT is presented to the /oauth2/token endpoint 3 hours later: id 09cfb961-291a-420f-b5cf-48c5c87a67cc, value baHneP4s0hBHPEk88GPC, lifetime 4 more hours

More details here: https://github.com/FusionAuth/fusionauth-issues/issues/2925

A refresh token is opaque; you cannot validate it yourself.

The general pattern for validating a refresh token is to use it to refresh the JWT, and if the refresh attempt fails, that indicates the refresh token is no longer valid.

You could also retrieve a user’s refresh tokens and compare it to the ones returned by FusionAuth.

More details:

https://fusionauth.io/docs/v1/tech/apis/jwt#refresh-a-jwt
https://fusionauth.io/docs/v1/tech/apis/jwt#retrieve-refresh-tokens

The short answer is however often you want, but at least once per device.

You basically can set up your refresh token policy to have your refresh tokens live for a very long time (as long as you are comfortable with the security risk; make sure to secure the refresh token carefully). That is controlled in in the application configuration: https://fusionauth.io/docs/v1/tech/core-concepts/applications/#jwt

Then, every time an access token expires, you can mint a new one with the refresh token. Here are the APIs you'd be interested in calling:

https://fusionauth.io/docs/v1/tech/apis/jwt/

the difference between a JWT/access token and a refresh token is that a refresh token can be revoked. Every time you present it to the Identity Provider/OAuth server, the OAuth server can check to see if the user has been banned, signed out or otherwise invalidated that token. (You can revoke a JWT, but it's a pain, typically.)

A refresh token is an engineering tradeoff. Without refresh tokens, you would have two unappetizing alternatives:

an access token that lived for a long time. In this case, if the access token is stolen, the attacker has a lot of time to access systems (or you need to have some kind of access token revocation strategy, which degrades the value of stateless access tokens). requiring the user to sign in every time the token expires. That gets old if the lifetime of the access token is minutes or hours. I even get annoyed every time Google asks me to re-sign into gmail, which only happens every week or two.

The spec requires a client to explicitly request a refresh token. With FusionAuth you have to request the offline_access scope (which is common for other auth providers, but I wasn't able to find it in the RFC), so it's a way to offer more flexibility.

This is a common issue, as there are a couple of prerequisite settings that you need to configure in order to get refresh tokens. When you are trying to get a refresh token and not seeing it, you should double check the following items:

you are passing a value of offline_access whenever a scope parameter is present. you have configured the application to generate refresh tokens if you are using OAuth, in the UI, it is in the OAuth tab; the field is Generate Refresh Tokens if you are using the Login API, it is in the Security tab under Login API Settings; the field is Generate Refresh Tokens. you are passing the client_id to the refresh grant request. This is required unless you are passing the Authorization header (which has the client_id in it). the user is registered to the application for which you are issuing a refresh token.

This is configurable. Go to https://fusionauth.io/docs/v1/tech/core-concepts/tenants/#jwt (though the screencaps are a bit out of date) but you’ll go there in your instance.

You’ll see refresh token settings.

If you’re using a fixed expiration, then it never expires based on last usage, but just based upon time since it was issued.

If you’re using a sliding window expiration, then it will expire based upon the time since it was last used.

There are two “worlds”, OAuth, and API only.

API world (JSON in body, proprietary to FusionAuth):

Application > Security > Login API Settings > Generate Refresh Tokens (Generate a a refresh token when using the Login API) Application > Security > Login API Settings > Enable JWT refresh (Allow a JWT to be refreshed using the /api/jwt/refresh API)

OAuth world (form params, in body and in request, standardized):

Application > OAuth > Generate Refresh Tokens (Generate a refresh token if offline_access scope was requested) Application > OAuth > Enabled Grants > Refresh Token (Allow a JWT to be refreshed using an refresh token) (edited)

If you are living in the OAuth world, then you can disable the API access, and just use the OAuth configuration. And vice versa.

They are globally unique, and they are deleted when a user is deleted. They must belong to a user.

Is this what you are looking for? https://fusionauth.io/docs/v1/tech/events-webhooks/events#jwt-refresh

Make sure you enable the webhook in the tenant as well as in the webhook definition.

Yes, a refresh token has a configured time to live (TTL). It can be configured at the Tenant or Application level.
More here: https://fusionauth.io/docs/v1/tech/core-concepts/tenants#jwt

My guess is you are missing the applicationId on the login API request.

A refresh token is per user per application, so passing that is required to provide refresh tokens (even though it is optional for the call to succeed).

Great thanks, that solved it.

@bboure You may be interested in this new feature from the 1.17.0 release, which allows for a sliding window of refresh tokens:

Sliding Window Refresh Token Expiration. By default the expiration of a refresh token is calculated from the time it was originally issued. Beginning in this release you may optionally configure the refresh token expiration to be based upon a sliding window. A sliding window expiration means that the expiration is calculated from the last time the refresh token was used. This expiration policy means that if you are using refresh tokens to maintain a user session, the session can be maintained as long as the user remains active. This expiration policy must be enabled at the tenant level, and may optionally be overridden by the Application JWT configuration.